Doc for Korean (spring-native\docs\src\site\ko\markdown\index.md) is added

개요

마이바티스 스프링 네이티브란?

마이바티스 스프링 네이티브는 Spring Native에 MyBatis 애플리케이션을 빠르게 만들 수 있도록 도와줍니다.

지원 기능

마이바티스 핵심

• SQL 주석(@Select/@Insert/기타 등등...)에 정적 SQLs과 동적 SQLs(OGNL 표현식으로) 작성
• 클래스경로와 로드 SQLs에 xml 파일 매퍼(mapper, 단계별 접근법) 기반으로 한 규칙 감지 (예시. 매퍼 인터페이스 정규화된 클래스 이름(FQCN)이 com.example.SampleMapper이면, com/example/SampleMapper.xml file를 찾아냅니다)
• SQL 제공자 사용(@SelectProvider/@InsertProvider/기타 등등...)
• Use built-in 2nd cache feature(in-memory 2nd cache)
• 빌트인 2단계 캐시 기능

마이바티스 스프링

• 자동 스캔 대신 @MapperScan을 이용한 스캔 매퍼 인터페이스

마이바티스 스프링 부트

• SqlSessionFactory 와 SqlSessionTemplate의 자동 설정합니다
• @Mapper표기 된 매퍼 인터페이스 자동 스캔합니다
• 환경설정 속성(application.properties)을 이용한 마이바티스 작동 습성 커스토마이즈 맞춤 설정합니다
• DI 컨테이너에서 마이바티스 컴포넌트(Interceptor, TypeHandler, LanguageDriver 그리고 DatabaseIdProvider)를 찾아냅니다
• DI 컨테이너를 구성하는 커스토마이저 컴포넌트 (ConfigurationCustomizer 또는 SqlSessionFactoryBeanCustomizer 가 적용 된 클래스)를 찾아냅니다

마이바티스 확장 모듈

• mybatis-thymeleaf 통합 지원
• mybatis-velocity 통합 지원
• mybatis-freemarker 통합 지원
• mybatis-dynamic-sql 통합 지원

마이바티스 스프링 네이티브

• @MyBatisResourcesScan를 이용한 타입 에일리어스, 타입 핸들러 그리고 xml file 매퍼 스캔
• 빌드 작동 시 @MyBatisResourcesScan를 이용하여 reflection hint로 어떤 클래스 든지 스캔
• 빌드 작동 시 @MyBatisResourcesScan를 이용하여 어떤 리소스 든지 스캔
• 파라미터 타입, 리턴 타입 그리고 네이티브 힌트(반사 힌트)에 대한 SQL 공급 타입 자동 등록 (표준 패턴만 지원)

알려진 제한사항

• MapperFactoryBean의 하위클래스 사용 시 작동하지 않을 수 있습니다. Fix early init of MapperFactoryBean kazuki43zoo/mybatis-spring-native#32 를 확인하세요
• 종속 타입(보류 파라미터와 리턴 타입)은 네이티브 힌트(반사 힌트)에 등록되지 않습니다
• 매퍼 인터페이스에 @Transactional 명기 시 빈 초기 설정 되지 않습니다. Fail bean initializing when specify @Transactional on mapper interface #2 를 확인하세요
• 기타 등등...

통합 지원 모듈

스프링-네이티브 작동을 위한 일반 구성을 제공합니다

사용법

@MyBatisResourcesScan 이용하기

In native-image, dynamic scanning does not work at runtime.
Therefore, we support to scan type aliases, type handlers and mapper xml files at build time using Spring AOT feature.
These resources will apply to MyBatis components using ConfigurationCustomizer and SqlSessionFactoryBeanCustomizer at startup time.

// ...
import org.mybatis.spring.nativex.MyBatisResourcesScan;
// ...
@MyBatisResourcesScan(typeAliasesPackages = "com.example.entity", mapperLocationPatterns = "mapper/**/*Mapper.xml")
@SpringBootApplication
public class MybatisSpringNativeSampleApplication {
  // ...
}

속성:

고지 사항

@MapperScan 사용

@MapperScan 사용 한다면, sqlSessionTemplateRef 또는 sqlSessionFactoryRef이 다음과 같이 명기되어야 합니다:

@MapperScan(basePackages = "com.example.mapper", sqlSessionTemplateRef = "sqlSessionTemplate")
@SpringBootApplication
public class MybatisSpringNativeSampleApplication {
  // ...
}

2nd cache 사용

만약 2nd cache 기능을 사용한다면, serialization hints 설정이 필요합니다.
따라서 JEP-290 serial filter로 설정을 권합니다 .

중요:

다음의 경고 로그가 출력 되는 경우, JEP-290 serial filter 정의를 추가하는 것을 고려하십시오.

2022-01-16 13:18:21.045  WARN 21917 --- [           main] o.apache.ibatis.io.SerialFilterChecker   : As you are using functionality that deserializes object streams, it is recommended to define the JEP-290 serial filter. Please refer to https://docs.oracle.com/pls/topic/lookup?ctx=javase15&id=GUID-8296D8E8-2B93-4B9A-856E-0A65AF9B8C66

serialization hints 설정 방법

@SerializationHint를 사용하여 설정합니다.

@NativeHint(serializables = @SerializationHint(types = { ArrayList.class, City.class, String.class, Integer.class, Number.class })) // Adding @SerializationHint
@SpringBootApplication
public class MybatisSpringNativeSampleApplication {
  // ...
}

JEP-290 serial filter 정의 방법

Define -Djdk.serialFilter(system properties) on buildArgs of native-maven-plugin at pom.xml.
pom.xml에 native-maven-plugin의 buildArgs 상의 -Djdk.serialFilter(시스템 속성) 설정

예시)

<plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-maven-plugin</artifactId>
  <version>${native-buildtools.version}</version>
  <extensions>true</extensions>
  <configuration>
    <buildArgs>
      <arg>-Djdk.serialFilter=org.mybatis.spring.nativex.sample.cache.*;java.util.*;java.lang.*;!*</arg> <!-- Adding definition -->
    </buildArgs>
  </configuration>
  <!-- ... -->
</plugin>

샘플

스프링-네이티브에 마이바티스 실행을 위한 예제를 제공합니다.

번역

마이바티스-스프링-네이티브에 대하여 다음 언어로 확인 가능합니다:

• English
• 한국어

Related Issues

• Translate doc for korean #29